home *** CD-ROM | disk | FTP | other *** search
/ Ham Radio 2000 #1 / Ham Radio 2000.iso / ham2000 / packet / terminal / winpack / wpext / wpextprg.doc < prev   
Encoding:
Text File  |  1996-06-02  |  9.0 KB  |  174 lines
  1. The ZIP file contains this document as well as some simple source code
  2. outlining how to produce an external program for Winpack 5.4.
  3.  
  4. Example source code is provided for both QuickBasic and C. Winpack itself
  5. comes with a Visual Basic example. An external program does NOT have to
  6. be a Windows program. You can write an external program in any language of
  7. your choice provided your program adheres to the principles outlined here.
  8.  
  9. Before examining the code provided, I should explain the general idea of
  10. external Winpack programs and how they work.
  11.  
  12. If you are using Winpack you will be familiar with some of the external
  13. programs available. These programs live in your WINPACK/EXTERN
  14. directory. You probably already have some such as FINGER and WINPLOG.
  15. External programs are NOT the same as servers in the true sense. There
  16. are differences in the way servers and external programs are written and
  17. used and this explanation refers only to external programs.
  18.  
  19. To launch an external program you generally give it a command such as
  20. /FINGER or /WINPLOG. You can either do this from the console in Winpack or
  21. a connected station can send the command. Winpack will look in the /EXTERN
  22. directory for a program with the name you have given and if such a program
  23. exists it will be executed.
  24.  
  25. Winpack passes certain information to the external program by means of the
  26. command line. There are always at least four arguments passed from Winpack
  27. to the external program as well as an optional fifth or more argument.
  28.  
  29. These arguments are:
  30.  
  31.         The status. This is a number starting at 0 for the first call to
  32.         this session. Subsequently the status number becomes whatever the
  33.         external program returned on the previous call. More on this a
  34.         bit later.
  35.  
  36.         pms_call. This is a string containing the Winpack operator's
  37.         callsign. i.e. it will generally be your callsign.
  38.  
  39.         first_name. This will be the first name of the Winpack operator.
  40.         i.e. it will be your first name as entered when you set up Winpack.
  41.  
  42.         connected_station. This is a string containing the callsign and
  43.         SSID of the station currently connected to you. If you launch the
  44.         external program yourself from within Winpack, it will be your
  45.         callsign. If a remote station invokes the external program it will
  46.         be their callsign.
  47.  
  48.         user_text. This will be a string containing any text the user
  49.         entered when calling the program. For example if you invoked the
  50.         external program FLUFF by typing  /FLUFF fred  then the text 'fred'
  51.         would be passed to the FLUFF external program as the fifth command
  52.         line argument.
  53.  
  54. All these command line arguments are MANDATORY except the user text. The 
  55. first four arguments are generated automatically by Winpack. The fifth (or
  56. subsequent) arguments will only exist if the user types something after
  57. the program name. Your program should always expect this format of command
  58. line arguments.
  59.  
  60. Let's have a look at an example. Suppose the information entered when
  61. you set up Winpack is as follows. Your callsign is VK2AAK, your first name
  62. is Andy. Another station with the callsign VK2AAA-9 is connected to you.
  63. Let's say the external program is named FLUFF.EXE and the connected user
  64. sends the command '/FLUFF help' to you.
  65. Winpack will look for the program FLUFF in the /EXTERN directory. If it
  66. finds it it will send the following command line to FLUFF.EXE.
  67.  
  68.         FLUFF.EXE 0 VK2AAK ANDY VK2AAA-9 help
  69.  
  70. The 0 is the status number. It is zero because this is the first time we
  71. have called FLUFF this session. The rest of the arguments are as outlined
  72. above.
  73.  
  74. OK so far?  Fine. Now the FLUFF program goes away and does whatever it was
  75. written to do. Before we are done though, we need to pass some information
  76. back to Winpack. All external programs do this by creating a disk file with
  77. the same name as the external program but with the suffix .REP. In the case
  78. of the FLUFF.EXE program, a disk file with the name FLUFF.REP would be
  79. created.
  80.  
  81. The format of the .REP file is very simple. The first line is the status
  82. number with which Winpack should call FLUFF the next time in this session.
  83. If the status number returned is less than zero then Winpack regards this
  84. as terminating the session and is therefore all done with FLUFF for the
  85. time being.
  86.  
  87. The next and subsequent lines are simply plain ASCII text which is returned
  88. to the user. Each of these text lines should contain just plain ASCII text
  89. and should be terminated with a carriage return and a line feed.
  90.  
  91. The source programs provided in this ZIP file are examples of single session
  92. external programs. i.e. they are called by Winpack, they do their thing and
  93. when finished executing, return with the status number set to -1.
  94.  
  95. The status number mechanism allows external programs to act intelligently.
  96. The external program can examine the status number and branch to other
  97. routines depending on the value. One important thing to remember if you
  98. write multiple session external programs is that you MUST store any interim
  99. data in a disk file at the end of each session before returning to Winpack. 
  100. If you don't, any program variables etc. will be lost.
  101.  
  102. OK, what do we get our external program to do? Well, that's up to you but
  103. you should write any external program in such a way that it executes quickly
  104. and terminates after each call. i.e. don't try writing an external program
  105. which takes half an hour to calculate PI to 1 million decimal places before
  106. returning to Winpack ... Winpack won't like it!
  107.  
  108. Examples of things you can do are looking up callbook information on a CD-ROM
  109. or controlling external equipment such as turning on a beacon. Your external
  110. program could send the contents of a file to the user such as the FINGER
  111. program does. There are plenty of possibilities ... use your imagination!
  112.  
  113.  
  114.  
  115. THE SOURCE CODE
  116.  
  117. First a few general notes about the source code provided. The BASIC code was
  118. written for Quick Basic 4.5 It is a perfect example of spaghetti programming
  119. with a liberal sprinkling of GOTO's. It is meant as an illustrative example
  120. of a Winpack external program, NOT an example of good programming techniques.
  121. The BASIC code complies OK and the resulting .EXE program has been tested
  122. with Winpack 5.43. There are a few things which should be done if you are
  123. going to use this code as a starting point for your own external program.
  124. It would be nice if the program first looked for an existing .REP file and
  125. deleted it before running. The supplied program just overwrites the .REP
  126. file it created last time it was called. I could have provided this function
  127. but it would have used QB45 libraries which you may not have so I left it
  128. out.
  129.  
  130. Also, the BASIC code handles the command line arguments in a different way to
  131. the C code. In C the user text is picked up as one word per argument from the
  132. command line. i.e if the user entered '/FLUFF fred andy' then 'fred' would
  133. be the fifth command line argument and 'andy' would be the sixth. The example
  134. C code only extracts five arguments from the command line so in the example
  135. above, the text 'andy' would simply be lost. It wouldn't cause any problems
  136. however.
  137.  
  138. In BASIC, the user text is picked up as an entire string complete with
  139. spaces etc. so in the above example, the fifth command line argument would
  140. be 'fred andy' and there would be no sixth argument.
  141.  
  142. The BASIC code is short and should be fairly self-explanatory. It assumes
  143. that it will reside in the WINPACK\EXTERN directory and that is where it
  144. puts the .REP response file because that is where Winpack will look for it.
  145.  
  146. The C code was compiled OK using both Microsoft Quick C and MIX software's
  147. Power C compilers. It is very straightforward code and should compile OK
  148. with any common or garden variety compiler. The C language extracts command
  149. line arguments in the argv[] array and the first entry in this array is
  150. always the program name. That is why the status is in argv[1], the callsign
  151. of the Winpack operator is in argv[2] etc. The program name will be in
  152. argv[0] and could be extracted and used to automatically generate the .REP
  153. file name. Be aware however that argv[0] will contain the entire path as
  154. well as the program name, e.g. it might contain C:\WINPACK\EXTERN\FLUFF.EXE.
  155.  
  156. The same comments apply as for the BASIC source. It is not meant as an
  157. example of good programming, just to illustrate how a Winpack external
  158. program works. Again, you could detect and delete an existing .REP file
  159. but as I don't know what compiler you might be using and what library
  160. functions it may have, I have kept it simple.
  161.  
  162. I hope you find the above information of some use. I don't expect or want
  163. any acknowledgement for the supplied code. Use it, modify it, do whatever
  164. you want with it. If you come up with any interesting external programs or
  165. ideas then by all means drop me a packet message to:
  166.         VK2AAK@VK2DYX.NSW.AUS.OC
  167. or send me an internet email to:
  168.         andykeir@midcoast.com.au
  169.  
  170. 73'
  171.  
  172. Andy. VK2AAK
  173.  
  174.